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ABOUT THIS CHAPTER 


This chapter describes the Vertical Retrace Manager, the part of the Operating 
System that schedules and performs recurrent tasks during vertical retrace 


interrupts. It describes how your application can install and remove its own 
recurrent tasks. 


You should already be familiar with: 


* events, as discussed in the Toolbox Event Manager chapter 
interrupts, as described in the Device Manager chapter 


e 
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ABOUT THE VERTICAL RETRACE MANAGER 


The Macintosh video circuitry generates a vertical retrace interrupt, also known 
as the vertical blanking (or VBL) interrupt, 60 times a second while the beam of 
the display tube returns from the bottom of the screen to the top to display the 
next frame. This interrupt is used as a convenient time for performing the 
following sequence of recurrent system tasks: 


1. Increment the number of ticks since system startup (every interrupt). 
You can get this number by calling the Toolbox Event Manager function 
TickCount. 

2. Check whether the stack has expanded into the heap; if so, it calls 
the System Error Handler (every interrupt). 

3. Handle cursor movement (every interrupt). 

4. Post a mouse event if the state of the mouse button changed from its 
previous state and then remained unchanged for four interrupts (every 
other interrupt). 

5. Reset the keyboard if it's been reattached after having been detached 
(every 32 interrupts). 

6. Post a disk-inserted event if the user has inserted a disk or taken 
any other action that requires a volume to be mounted (every 30 
interrupts). 


These tasks must execute at regular intervals based on the "heartbeat" of the 
Macintosh, and shouldn't be changed. 


Tasks performed during the vertical retrace interrupt are known as VBL tasks. An 
application can add any number of its own VBL tasks for the Vertical Retrace 
Manager to execute. VBL tasks can be set to execute at any frequency (up to once 
per vertical retrace interrupt). For example, an electronic mail application 
might add a VBL task that checks every tenth of a second (every six interrupts) 
to see if it has received any messages. These tasks can perform any desired 
action as long as they don't make any calls to the Memory Manager, directly or 
indirectly, and don't depend on handles to unlocked blocks being valid. They 
must preserve all registers other than AO-A3 and DO-D3. If they use application 
globals, they must also ensure that register A5 contains the address of the 
boundary between the application globals and the application parameters; for 
details, see SetCurrentA5 and SetA5 in Macintosh Technical Note #208. 


eeeClick on the X-Ref button, and refer to Technical Note #208.¢ee 


Warning: When interrupts are disabled (such as during a disk access), or 
when VBL tasks take longer than about a sixtieth of a second to 
perform, one or more vertical retrace interrupts may be missed, 
thereby affecting the performance of certain VBL tasks. For 
instance, while a disk is being accessed, the updating of the 
cursor movement may be irregular. 


Note: To perform periodic actions that do allocate and release memory, you 
can use the Desk Manager procedure SystemTask. Or, since the first 
thing the Vertical Retrace Manager does during a vertical retrace 
interrupt is increment the tick count, you can call TickCount 
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repeatedly and perform periodic actions whenever a specific number 
of ticks have elapsed. 


Information describing each VBL task is contained in the vertical retrace queue. 
The vertical retrace queue is a standard Macintosh Operating System queue, as 
described in the Operating System Utilities chapter. Each entry in the vertical 
retrace queue has the following structure: 


TYPE VBLTask = RECORD 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
vblAddr: ProcPtr; {pointer to task} 
vblCount: INTEGER; {task frequency} 
vblPhase: INTEGER {task phase} 
END; 


QLink points to the next entry in the queue, and qlype indicates the queue type, 
which must be ORD(vType). 


VBLAddr contains a pointer to the task. VBLCount specifies the number of ticks 
between successive calls to the task. This value is decremented each sixtieth of 
a second until it reaches 0, at which point the task is called. The task must 
then reset vblCount, or its entry will be removed from the queue after it has 
been executed. VBLPhase contains an integer (smaller than vblCount) used to 
modify vblCount when the task is first added to the queue. This ensures that two 
or more tasks added to the queue at the same time with the same vblCount value 
will be out of phase with each other, and won't be called during the same 
interrupt. Unless there are many tasks to be added to the queue at the same 
time, vblPhase can usually be set to 0. 


The Vertical Retrace Manager uses bit 6 of the queue flags field in the queue 
header to indicate when a task is being executed: 


Bit Meaning 
6 Set if a task is being executed 


Assembly-language note: Assembly-programmers can use the global constant 
inVBL to test this bit. 
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USING THE VERTICAL RETRACE MANAGER 


The Vertical Retrace Manager is automatically initialized each time the system 
starts up. To add a VBL task to the vertical retrace queue, call VInstall. When 
your application no longer wants a task to be executed, it can remove the task 
from the vertical retrace queue by calling VRemove. A VBL task shouldn't call 
VRemove to remove its entry from the queue—-either the application should call 
VRemove, or the task should simply not reset the vblCount field of the queue 
entry. 


Assembly-language note: VBL tasks may use registers AQ-A3 and DQ-D3, and 
must save and restore any additional registers 
used. They must exit with an RTS instruction. 


If you'd like to manipulate the contents of the vertical retrace queue directly, 
you can get a pointer to the header of the vertical retrace queue by calling 
GetVBLQHdr. 


With the advent of slots, a variety of screens are available, each with 
potentially different vertical retrace periods. The Vertical Retrace Manager 
has been extended to provide flexible, slot-specific video-interrupt handling on 
the Macintosh II. These changes are mostly transparent to existing 
applications. 


Several video cards can be installed on a single system. The user can, at any 
time, designate a particular slot as the primary video slot for the system. If 
at system startup, no device is designated, the Start Manager selects one (see 
the Start Manager chapter for details). 


Instead of maintaining a single vertical retrace queue, the Vertical Retrace 
Manager now maintains a separate queue for each connected video device; 
associated with each queue is the rate at which the device's vertical retrace 
interrupt occurs. When interrupts occur for a particular video slot, the 
Vertical Retrace Manager executes any tasks in the queue for that slot. 


For compatibility with existing software, a special system-generated interrupt 
handles the execution of tasks previously performed during the vertical retrace 
interrupt. This special interrupt, generated 60.15 times a second (identical to 
the retrace rate on the Macintosh Plus), mimics the vertical retrace interrupt 
and ensures that application tasks installed with the VInstall function, as well 
as periodic system tasks such as updating the tick count and checking whether 
the stack has expanded into the heap, are performed as uSual. 


You can still use the VInstall function as a way of performing recurrent tasks 
based on ticks. Be aware, however, that these tasks will no longer be tied to 
the actual retrace rate of the video screen. 


To install a task whose execution is tied to the vertical retrace period of a 
particular video device, call SlotVInstall using the VBLTask queue element; as 
before qlype must be ORD(vType). The Vertical Retrace Manager interprets the 
vblCount field in terms of the rate that the specified slot generates vertical 
retrace interrupts. On the current Macintosh II monitors, for instance, the 
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interrupt occurs every 1/67th of a second; specifying a vblCount of 10 means 
that the task will be executed every 10/67ths of a second. The value of 
vblCount is decremented every 1/67th of a second until it reaches 0, at which 
point the task is called. To remove a slot-specific task, call SlotVRemove. 


The AttachVBL function is used primarily by the Start Manager and Control Panel 
for designating the primary video device; only applications that shift between 
multiple video cards will need to call this routine. 


Slot interrupt handlers for video cards need to call the DoVBLTask function; 
this causes the Vertical Retrace Manager to execute any tasks in the queue for 
that slot. 
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VERTICAL RETRACE MANAGER ROUTINES 


FUNCTION VInstall (vblTaskPtr: QElemPtr) : OSErr; 


Trap macro VInstall 
On entry AQ: vblTaskPtr (pointer) 
On exit DO: result code (word) 


VInstall adds the VBL task specified by vblTaskPtr to the vertical retrace 
queue. Your application must fill in all fields of the task except gLink. 
VInstall returns one of the result codes listed below. 


Result codes noErr No error 
vTypErr QType field isn't ORD(vType) 


FUNCTION SlotVInstall (vblTaskPtr: QElemPtr; theSlot: INTEGER) : OSErr; 


Trap macro SlotVInstall 

On entry AQ: vblTaskPtr (pointer) 
DO: theSlot (word) 

On exit DO: result code (word) 


SltotVInstall is identical in function to the VInstall function except that it 
installs the task in the queue for the device specified by theSlot. 


Result codes noErr No error 
vTypErr Invalid queue element 
slotNumErr Invalid slot number 


FUNCTION VRemove (vblTaskPtr: QElemPtr) : OSErr; 


Trap macro —_VRemove 
On entry AQ: vblTaskPtr (pointer) 
On exit DO: result code (word) 


VRemove removes the VBL task specified by vblTaskPtr from the vertical retrace 
queue. It returns one of the result codes listed below. 


Result codes noErr No error 
vTypErr QType field isn't ORD(vType) 
gErr Task entry isn't in the queue 


FUNCTION SlotVRemove (vblTaskPtr: QElemPtr; theSlot: INTEGER) : OSErr; 


Trap macro —_SlotVRemove 

On entry AQ: vblTaskPtr (pointer) 
DO: theSlot (word) 

On exit DO: result code (word) 


SlotVRemove is identical in function to the VRemove function except that it 
removes the task from the queue for the slot specified by theSlot. 
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Result codes noErr No error 
vTypErr Invalid queue element 
slotNumErr Invalid slot number 


FUNCTION GetVBLQHdr : QHdrPtr; [Not in ROM] 
GetVBLQHdr returns a pointer to the header of the vertical retrace queue. 


Assembly-language note: The global variable VBLQueue contains the header 
of the vertical retrace queue. 


FUNCTION AttachVBL (theSlot: INTEGER) : OSErr; 


Trap macro _AttachVBL 
On entry DO: theSlot (word) 
On exit DO: result code (word) 


AttachVBL makes theSlot the primary video slot, allowing correct cursor 
updating. 


Result codes noErr No error 
slotNumErr Invalid slot number 


FUNCTION DoVBLTask (theSlot: INTEGER) : OSErr; 


Trap macro —DoVBLTask 
On entry DO: theSlot (word) 
On exit DO: result code (word) 


Note: To reduce overhead at interrupt time, instead of executing the 
_DoVBLTask trap you can load the jump vector jDoVBLTask into an 
address register and execute a JSR instruction using that register. 


DoVBLTask causes any VBL tasks in the queue for the specified slot to be 
executed. If the specified slot is the primary video slot, the position of the 
cursor will also be updated. 


Result codes noErr No error 
slotNumErr Invalid slot number 
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SUMMARY OF THE VERTICAL RETRACE MANAGER 


Constants 
CONST 
{ Result codes } 
noErr = 0; {no error} 
gErr = -1; {task entry isn't in the queue} 
vTypErr = -2; {qType field isn't ORD(vType) } 
Data Types 
TYPE 
VBLTask = RECORD 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
vblAddr: ProcPtr; {pointer to task} 
vblCount: INTEGER; {task frequency} 
vblPhase: INTEGER {task phase} 
END; 
Routines 


FUNCTION VInstall 
FUNCTION SlotVInstall 


vblTaskPtr: QElemPtr) : OSErr; 

vblTaskPtr: QElemPtr; theSlot: INTEGER) : OSErr; 
FUNCTION VRemove vblTaskPtr: QElemPtr) : OSErr; 

FUNCTION SlotVRemove vblTaskPtr: QElemPtr; theSlot: INTEGER) : OSErr; 
FUNCTION GetVBLQHdr : QHdrPtr; [Not in ROM] 

FUNCTION AttachVBL (theSlot: INTEGER) : OSErr; 

FUNCTION DoVBLTask (theSlot: INTEGER) : OSErr; 


ee 


Assembly-Language Information 
Constants 
inVBL .EQU 6 ;set if Vertical Retrace Manager is executing a task 


; Result codes 


noErr .EQU 0 ;no error 
gErr . EQU -1 ;task entry isn't in the queue 
vTypErr .EQU -2 ;qlype field isn't vType 


Structure of Vertical Retrace Queue Entry 
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qLink Pointer to next queue entry 
qType Queue type (word) 

vblAddr Address of task 

vblCount Task frequency (word) 
vblPhase Task phase (word) 


Routines 
Trap macro On entry On exit 
_VInstall AO: vblTaskPtr (ptr) DO: result code (word) 


_SlotVInstall AQ: vblTaskPtr (pointer) DO: result code (word) 
DO: theSlot (word) 

_VRemove AO: vblTaskPtr (ptr) DO: result code (word) 

_SlotVRemove AO: vblTaskPtr (pointer) DO: result code (word) 
DO: theSlot (word) 


_AttachVBL DO: theSlot (word) DO: result code (word) 
_DoVBLTask DO: theSlot (word) DO: result code (word) 
Variables 

VBLQueue Vertical retrace queue header (10 bytes) 


jDoVBLTask Jump vector for DoVBLTask routine 
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Further Reference: 


Toolbox Event Manager 

Device Manager 

Start Manager 

Technical Note #180, MultiFinder Miscellanea 

Technical Note #208, Setting and Restoring A5 
Technical Note #221, NuBus Interrupt Latency 

"Macintosh Family Hardware Reference" 


END OF DOCUMENT 
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